DirectOutput SDK Reference

Table of Contents

Overview

The DirectOutput SDK can be used by programmers to write applications and application plug-ins that use DirectOutput compatible devices to display information. These commponents can be written in C or C++. Typically these components will be used to do the following:
DirectOutput uses a concept of Pages to seperate data. Each application can add one or more pages to the device, and each page holds a collection of output settings. The user navigates between pages with the NextPage and PreviousPage buttons on the device.
For more information about DirectOutput, please visit the forum at www.saitekforum.com
Please direct all DirectOutput programming questions and problems to the forum.

Setup

To build applications that use DirectOutput, you must create your application to load and import function calls from the dynamic library DirectOutput.dll.

Device Data Sheets


DirectOutput API Reference

This section lists all the API functions and structures required to build DirectOutput enabled applications.
FunctionDescription
DirectOutput_InitializeInitialize the DirectOutput library
DirectOutput_DeinitializeClean up the DirectOutput library
DirectOutput_RegisterDeviceCallbackRegister a callback function to be called when a device is added or removed
DirectOutput_EnumerateEnumerate all currently attached DirectOutput devices.
DirectOutput_GetDeviceTypeGets an identifier that identifies the device.
DirectOutput_GetDeviceInstanceGets an instance identifier to used with Microsoft DirectInput.
DirectOutput_GetSerialNumberGets serial number to used with Microsoft DirectInput.
DirectOutput_SetProfileSets the profile on this device.
DirectOutput_RegisterSoftButtonCallbackRegisters a callback with a device, that gets called whenever a "Soft Button" is pressed or released.
DirectOutput_RegisterPageCallbackRegisters a callback with a device, that gets called whenever the active page is changed.
DirectOutput_AddPageAdds a page to the specified device.
DirectOutput_RemovePageRemoves a page.
DirectOutput_SetLedSets the state of a given LED indicator.
DirectOutput_SetStringSets a string value of a given string.
DirectOutput_SetImageSets the image data of a given image.
DirectOutput_SetImageFromFileSets the image from an image file.
DirectOutput_StartServerStarts a Server application on the device.
DirectOutput_CloseServerInforms a Server application on the device to terminate.
DirectOutput_SendServerMsgSends a message to a Server application on the device.
DirectOutput_SendServerFileSends a header and file to the Server application on the device.
DirectOutput_SaveFileSaves a file on the device.
DirectOutput_DisplayFileDisplays a file thats been saved on the device.
DirectOutput_DeleteFileDeletes a file from the device.

Callback FunctionDescription
DirectOutput_Enumerate_CallbackCalled when DirectOutput_Enumerate is called.
DirectOutput_Device_CallbackCalled whenever a DirectOutput device is added or removed.
DirectOutput_SoftButton_CallbackCalled whenever a "Soft Button" is pressed or released.
DirectOutput_Page_CallbackCalled whenever the active page is changed.


DirectOutput_Initialize

Syntax


    HRESULT DirectOutput_Initialize(const wchar_t* wszAppName);

Parameters

wszAppName
[in] A null-terminated wide character string that specifies the name of the application. Optional

Return Values

S_OK
The call completed successfully.
E_OUTOFMEMORY
There was insufficient memory to complete this call.
E_INVALIDARG
The argument is invalid.
E_HANDLE
The DirectOutputManager prcess could not be found.

Notes

This function must be called before calling any others. Call this function when you want to initialize the DirectOutput library.

DirectOutput_Deinitialize

Syntax


    HRESULT DirectOutput_Deinitialize();

Parameters

This function does not take any parameters

Return Values

S_OK
The call completed successfully.
E_HANDLE
DirectOutput was not initialized or was already deinitialized.

Notes

This function must be called before termination. Call this function to clean up any resources allocated by DirectOutput_Initialize

DirectOutput_RegisterDeviceCallback

Syntax


    HRESULT DirectOutput_RegisterDeviceCallback(Pfn_DirectOutput_Device_Callback pfnCallback, void* pvParam);

Parameters

pfnCallback
[in] A pointer to the callback function to be called whenever a device is added or removed.
pvParam
[in] An application supplied context pointer that will be passed to the callback function.

Return Values

S_OK
The call completed successfully
E_HANDLE
DirectOutput was not initialized.

Notes

Passing a NULL function pointer will disable the callback.

DirectOutput_Enumerate

Syntax


    HRESULT DirectOutput_Enumerate(Pfn_DirectOutput_EnumerateCallback pfnCallback, void* pvParam);

Parameters

pfnCallback
[in] A pointer to the callback function to be called for each detected device.
pvParam
[in] An application supplied contect pointer that will be passed to the callback function.

Return Values

S_OK
The call completed successfully.
E_HANDLE
DirectOutput was not initialized.

Notes

This function has changed from previous releases.

DirectOutput_GetDeviceType

Syntax


    HRESULT DirectOutput_GetDeviceType(void* hDevice, LPGUID pGuidType);

Parameters

hDevice
[in] A void pointer handle that was supplied in the device change callback.
pGuidType
[out] A pointer to a GUID value that will recieve the type identifier of this device.

Return Values

S_OK
The call completed successfully.
E_INVALIDARG
An argument is invalid.
E_HANDLE
The device handle specified is invalid.

Notes

Refer to the list of type GUIDs to find out about what features are available on each device.

DirectOutput_GetDeviceInstance

Syntax


    HRESULT DirectOutput_GetDeviceInstance(void* hDevice, LPGUID pGuidInstance);

Parameters

hDevice
[in] A void pointer handle that was supplied in the device change callback.
pGuidInstance
[out] A pointer to a GUID value that will recieve the instance identifier of this device.

Return Values

S_OK
The call completed successfully.
E_NOTIMPL
This device does not support DirectInput.
E_INVALIDARG
An argument is invalid.
E_HANDLE
The device handle specified is invalid.

Notes

Use pGuidInstance in IDirectInput::CreateDevice to create the IDirectInputDevice that corrresponds to this DirectOutput device.

    GUID gdInstance;
    HRESULT hr = DirectOutput_GetDeviceInstance(hDevice, &gdInstance);
    if (hr == S_OK)
    {
        IDirectInputDevice* pDevice;
        hr = pDirectInput->CreateDevice(gdInstance, &pDevice, NULL);
        if (SUCCEEDED(hr))
        {
            // setup pDevice as a joystick and start polling for data.
        }
    }



DirectOutput_GetSerialNumber

Syntax


    HRESULT DirectOutput_GetSerialNumber(void* hDevice, wchar_t* pszSerialNumber, DWORD dwSize);

Parameters

hDevice
[in] A void pointer handle that was supplied in the device change callback.
pszSerialNumber
[out] String buffer to hold the serial number of the device. The String can be empty if no serial number associated with the device.
dwSize
[in] Specify the number of characters of the string buffer. The value of this parameter shouldn't be greater than 16. Otherwise, the string buffer is truncated into 16 characters.

Return Values

S_OK
The call completed successfully.


DirectOutput_SetProfile

Syntax


    HRESULT DirectOutput_SetProfile(void* hDevice, DWORD cchFilename, const wchar_t* wszFilename);

Parameters

hDevice
[in] A handle to a device.
cchFilename
[in] The number of wide characters in the filename parameter, wszFilename.
wszFilename
[in] A NULL-terminated string containing the full path and filename of the profile to activate.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support profiling.
E_INVALIDARG
cchFilename is zero OR wszFilename is NULL.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes

Passing in a NULL pointer to wszFilename and 0 to cchFilename will clear the current profile.

DirectOutput_RegisterSoftButtonCallback

Syntax


    HRESULT DirectOutput_RegisterSoftButtonCallback(void* hDevice, Pfn_DirectOutput_SoftButton_Callback pfnCallback, void* pvContext);

Parameters

hDevice
[in] A handle to a device.
pfnCallback
[in] A pointer to the callback function to be called whenever a "Soft Button" is pressed or released.
pvContext
[in] An application supplied context pointer that will be passed to the callback function.

Return Values

S_OK
The call completed successfully.
E_HANDLE
The device handle specified is invalid.

Notes

Passing a NULL function pointer will disable the callback.

DirectOutput_RegisterPageCallback

Syntax


    HRESULT DirectOutput_RegisterPageCallback(void* hDevice, Pfn_DirectOutput_Page_Callback pfnCallback, void* pvContext);

Parameters

hDevice
[in] A handle to a device.
pfnCallback
[in] A pointer to the callback function to be called whenever the active page is changed.
pvContext
[in] An application supplied context pointer that will be passed to the callback function.

Return Values

S_OK
The call completed successfully.
E_HANDLE
The device handle specified is invalid.

Notes

Adding a page with an existing page id is not allowed. The page id only has to be unique on a per application basis. The callback will not be called when a page is added as the active page with a call to DirectOutput_AddPage(hDevice, dwPage, wszName, FLAG_SET_AS_ACTIVE); Passing a NULL function pointer will disable the callback.

DirectOutput_AddPage

Syntax


    HRESULT DirectOutput_AddPage(void* hDevice, DWORD dwPage, DWORD dwFlags);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwFlags
[in] If this contains FLAG_SET_AS_ACTIVE, then this page will become the active page. If zero, this page will not change the active page.

Return Values

S_OK
The call completed successfully.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_INVALIDARG
The dwPage parameter already exists.
E_HANDLE
The device handle specified is invalid.

Notes

Only one page per-application per-device should have dwFlags contain FLAG_SET_AS_ACTIVE. The plugin is not informed about the active page change if the FLAG_SET_AS_ACTIVE is set.

DirectOutput_RemovePage

Syntax


    HRESULT DirectOutput_RemovePage(void* hDevice, DWORD dwPage);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.

Return Values

S_OK
The call completed successfully.
E_INVALIDARG
The dwPage argument does not reference a valid page id.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_SetLed

Syntax


    HRESULT DirectOutput_SetLed(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD dwValue);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the LED. Refer to the data sheet for each device to determine what LEDs are present.
dwValue
[in] The numeric value of a given state of a LED. Refer to the data sheet for each device to determine what are legal values.

Return Values

S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not specifiy a valid LED id.
E_HANDLE
The device handle specified is invalid.

Notes

dwValue is usually 0 (off) or 1 (on).

DirectOutput_SetString

Syntax


    HRESULT DirectOutput_SetString(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD cchValue, const wchar_t* wszValue);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the string. Refer to the data sheet for each device to determine what strings are present.
cchValue
[in] The number of characters (wchar_t) in the string data.
wszValue
[in] A null-terminated wide character string that specifies the value to display. Providing a null pointer will clear the string.

Return Values

S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not reference a valid string id.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_SetImage

Syntax


    HRESULT DirectOutput_SetImage(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD cbValue, const LPBYTE pbValue);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the image. Refer to the data sheet for each device to determine what images are present.
cbValue
[in] The number of bytes in pbValue
pbValue
[in] An array of bytes of cbValue bytes long that represents the raw bitmap to display on the screen.

Return Values

S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not reference a valid image id.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes

The buffer passed must be the correct size for the specified image.
This call sends the buffer directly to the device, so the format of the data is device specific. Refer to the device data sheet for more details on the image data format.

DirectOutput_SetImageFromFile

Syntax


    HRESULT DirectOutput_SetImageFromFile(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD cchFilename, const wchar_t* wszFilename);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] A numeric identifier of a page. Usually this is the 0 based number of the page.
dwIndex
[in] A numeric identifier of the image. Refer to the data sheet for each device to determine what images are present.
cchFilename
[in] The number of characters (wchar_t) in the filename string.
wszFilename
[in] The NULL-terminated full path to the image to load.

Return Values

S_OK
The call completes successfully.
E_PAGENOTACTIVE
The specified page is not active. Displaying information is not permitted when the page is not active.
E_INVALIDARG
The dwPage argument does not reference a valid page id, or the dwIndex argument does not reference a valid image id.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes

This call reads all the data from the file and sends this directly to the device, so the format of the data is device specific. Refer to the device data sheet for more details on the image data format.
Unless specified by the device data sheet you cannot use this function to directly send image files to the device.

DirectOutput_StartServer

Syntax


    HRESULT DirectOutput_StartServer(void* hDevice, DWORD cchFilename, const wchar_t* wszFilename, LPDWORD pdwServerId, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
cchFilename
[in] The number of characters (wchar_t) in the filename string.
wszFilename
[in] The NULL-terminated full path to the Server application.
pdwServerId
[out] A pointer to a DWORD that recieves this server id.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_CloseServer

Syntax


    HRESULT DirectOutput_CloseServer(void* hDevice, DWORD dwServerId, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
dwServerId
[in] The server id to close.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_SendServerMsg

Syntax


    HRESULT DirectOutput_SendServerMsg(void* hDevice, DWORD dwServerId, DWORD dwRequest, DWORD dwPage, DWORD cbIn, const void* pvIn, DWORD cbOut, void* pvOut, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
dwServerId
[in] The server id to close.
dwPage
[in] The page id that is related to this server.
cbIn
[in] The number of bytes in the input buffer.
pvIn
[in] The input buffer of this message.
cbOut
[in] The number of bytes in the output buffer.
pvOut
[out] A pointer to a caller allocated buffer that recieves the output data.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_PAGENOTACTIVE
The specified page is not active and the server application attempted to access the display.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes

The page does have to be active if the server accesses the display. The page does not have to be active if the server does not access the display.

DirectOutput_SendServerFile

Syntax


    HRESULT DirectOutput_SendServerFile(void* hDevice, DWORD dwServerId, DWORD dwRequest, DWORD dwPage, DWORD cbInHdr, const void* pvInHdr, DWORD cchFile, const wchar_t* wszFile, DWORD cbOut, void* pvOut, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
dwServerId
[in] The server id to close.
dwPage
[in] The page id that is related to this server.
cbInHdr
[in] The number of bytes in the input buffer header.
pvInHdr
[in] The input buffer of this message's header.
cchFile
[in] The number of characters (wchar_t) in the filename.
wszFile
[in] A NULL-terminated string of the full path to the file to send.
cbOut
[in] The number of bytes in the output buffer.
pvOut
[out] A pointer to a caller allocated buffer that recieves the output data.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support server applications.
E_PAGENOTACTIVE
The specified page is not active and the server application attempted to access the display.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes

The page does have to be active if the server accesses the display. The page does not have to be active if the server does not access the display.

DirectOutput_SaveFile

Syntax


    HRESULT DirectOutput_SaveFile(void* hDevice, DWORD dwPage, DWORD dwFile, DWORD cchFilename, const wchar_t* wszFilename, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
dwPage
The page id of the page to associate with this file.
dwFile
[in] The caller supplied file id to use for this file.
cchFilename
[in] The number of characters (wchar_t) in the filename.
wszFilename
[in] A NULL-terminated string of the full path to the file to save.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support saving files.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_DisplayFile

Syntax


    HRESULT DirectOutput_DisplayFile(void* hDevice, DWORD dwPage, DWORD dwIndex, DWORD dwFile, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] The page id of the page to associate with this file.
dwIndex
[in] The index of the image to display this file on.
dwFile
[in] The caller supplied file id to use for this file.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support displaying files.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_DeleteFile

Syntax


    HRESULT DirectOutput_DeleteFile(void* hDevice, DWORD dwPage, DWORD dwFile, PSRequestStatus psStatus);

Parameters

hDevice
[in] A handle to a device.
dwPage
[in] The page id of the page to associate with this file.
dwFile
[in] The caller supplied file id to use for this file.
psStatus
[out] A pointer to a SRequestStatus structure to recieve extended error information. Can be NULL.

Return Values

S_OK
The call completes successfully.
E_NOTIMPL
The device does not support deleting files.
E_OUTOFMEMORY
Insufficient memory to complete the request.
E_HANDLE
The device handle specified is invalid.

Notes



DirectOutput_Enumerate_Callback

Syntax


    void __stdcall DirectOutput_Enumerate_Callback(void* hDevice, void* pvContext);

Parameters

hDevice
[in] A handle to the device that changed.
pvContext
[in] The application defined context value passed to DirectOutput_Enumerate

Return Values

This callback does not return a value.

Notes

This callback will be called whenever a DirectOutput is present during a call to DirectOutput_Enumerate.


DirectOutput_Device_Callback

Syntax


    void __stdcall DirectOutput_Device_Callback(void* hDevice, bool bAdded, void* pvContext);

Parameters

hDevice
[in] A handle to the device that changed.
bAdded
[in] true if the device was added, false if the device was removed.
pvContext
[in] The application defined context value passed to DirectOutput_RegisterDeviceCallback

Return Values

This callback does not return a value.

Notes

This callback will be called whenever a DirectOutput device is added to, or removed from, the system. Once a device has been removed, do not call any functions using the specified device handle (hDevice).

DirectOutput_SoftButton_Callback

Syntax


    void __stdcall DirectOutput_SoftButton_Callback(void* hDevice, DWORD dwButtons, void* pvContext);

Parameters

hDevice
[in] A handle to the device that changed.
dwButtons
[in] A bit mask that specifies what buttons are pressed. Refer to the device data sheet to determine the allowed buttons.
pvContext
[in] The application defined context value passed to DirectOutput_RegisterSoftButtonCallback

Return Values

This callback does not return a value.

Notes

This callback will be called whenever a soft button's state changes. You will only recieve this notification if one of the pages you added is currently active.

DirectOutput_Page_Callback

Syntax


    void __stdcall DirectOutput_Page_Callback(void* hDevice, DWORD dwPage, bool bActivated, void* pvContext);

Parameters

hDevice
[in] A handle to the device that changed.
dwPage
[in] The page identifier passed to DirectOutput_AddPage of this page.
bActivated
[in] true if this page has become the active page, false if this page was the active page.
pvContext
[in] The application defined context value passed to DirectOutput_RegisterPageCallback

Return Values

This callback does not return a value.

Notes

This callback is called when a page changed. You will only recieve notifications about pages you added.

Samples

Samples can be found under the <SDK>\Samples folder
Sample NameDescriptionRequirements
TestWindows application (using WTL) that demonstrates device enumeration, softbuttons and displaying information on the devicesMicrosoft Visual Studio Express (C++), Platform SDK, WTL